Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Truncating Strings Before Converting Them /

TruncateForUnicodeToText

Identifies where your application can safely break a Unicode string to be converted to any encoding so that the string is broken in a way that preserves the text element integrity.

pascal OSStatus TruncateForUnicodeToText (
      ConstUnicodeToTextInfo iUnicodeToTextInfo,
      ByteCount iSourceLen, 
      ConstUniCharArrayPtr iSourceStr, 
      OptionBits iControlFlags, 
      ByteCount iMaxLen, 
      ByteCount *oTruncatedLen);

iUnicodeToTextInfo

A Unicode converter object UnicodeToTextInfo (page 120) for the Unicode string to be divided up. The TruncateForUnicodeToText function does not modify the contents of this private structure.

iSourceLen

The length in bytes of the Unicode string to be divided up.

iSourceStr

A pointer to the Unicode string to be divided up.

iControlFlags

Truncation control flags. Specify the flag kUnicodeStringUnterminatedMask if truncating a buffer of text that belongs to a longer stream containing a subsequent buffer of text that could have characters belonging to a text element that begins at the end of the current buffer. If you set this flag, typically you would set the iMaxLen parameter equal to iSourceLen. For information on the flag kUnicodeStringUInterminatedMask, see "Conversion Control Flags" (page 110).

iMaxLen

The maximum allowable length of the string to be truncated. This must be less than or equal to iSourceLen.

oTruncatedLen

A pointer to a value of type ByteCount. On output, this value contains the length of the longest portion of the Unicode source string, pointed to by the iSourceStr parameter, that is less than or equal to the value of the iMaxLen parameter. This returned parameter identifies the byte after which you can truncate the string.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

Your application can use this function to divide up a Unicode string properly truncating each portion before you call ConvertFromUnicodeToText or ConvertFromUnicodeToScriptCodeRun to convert the string. You can call this function repeatedly to properly truncate a text segment, each time identifying the new beginning of the string, until the last portion of the text is less than or equal to the maximum allowable length. Each time you use the function, you get a properly terminated string within the allowable length range. You use the function as many times as necessary to be able to convert the entire text segment.

Because this function does not modify the contents of the Unicode converter object, you can call this function between conversion calls.

In addition to resource errors, the functions may return any of the following result codes: paramErr, kTECGlobalsUnavailableErr, kTECTableFormatErr, kTECPartialCharErr (if truncating UTF-8), kTECIncompleteElementErr, or kTextUndefinedElementErr. If the result code is not noErr, then the value returned by the oTruncatedLen parameter is invalid.